using System;
using System.Collections.Generic;
using System.Text;
using CookComputing.XmlRpc;

namespace EnsoNetServer
{
    /// <summary>
    /// Main interface to the Enso endpoint.
    /// </summary>
    public interface IEnso
    {
        /// <summary>
        /// Displays the given message text XML fragment as a transparent message.
        /// </summary>
        /// <param name="text">the message text XML fragment to be displayed.</param>
        /// <returns>This function always returns True.</returns>
        [XmlRpcMethod("displayMessage")]
        bool DisplayMessage(string text);

        /// <summary>
        /// Retrieves the user's current file selection.
        /// </summary>
        /// <returns>List of unicode strings.  If the user has selected one or
        /// more files in the current application, each item in the list
        /// is the full pathname to one of the files in the selection.
        /// If no files are selected, or if there's an error trying to
        /// get the files, returns an empty list.</returns>
        [XmlRpcMethod("getFileSelection")]
        string[] GetFileSelection();

        /// <summary>
        /// Retrieves the user's current text selection.
        /// </summary>
        /// <returns>Unicode string representing the user's current selection. If
        /// the user has no selection, or if the selection is not text,
        /// then the return value is an empty string.</returns>
        [XmlRpcMethod("getUnicodeSelection")]
        string GetUnicodeSelection();

        /// <summary>
        /// Inserts unicode text at the current cursor location in the
        /// user's current application.  If the user currently has a text
        /// selection, the text is appended to it.  If the text cannot be
        /// inserted, a transparent message is displayed and the text is
        /// placed in Enso's put buffer.
        /// </summary>
        /// <param name="text">the unicode text to be inserted.</param>
        /// <param name="fromCommand">the name of the command that is inserting the
        /// text. This is entirely for informational purposes and will
        /// be displayed to the user if the text cannot be inserted.</param>
        /// <returns>This function always returns True.</returns>
        [XmlRpcMethod("insertUnicodeAtCursor")]
        bool InsertUnicodeAtCursor(string text, string fromCommand);

        /// <summary>
        /// Registers an Enso Extension Command with Enso.  Once this
        /// function is called, an end-user may invoke the command via
        /// Enso's Command Quasimode.
        /// </summary>
        /// <param name="url">the URL for the Enso Extension endpoint.</param>
        /// <param name="name">the name of the command, in Command Expression format.</param>
        /// <param name="description">the one-line descriptive text for the command,
        /// displayed on the top line of the Command Quasimode when the
        /// command name has been entered into the quasimode.</param>
        /// <param name="help">the XHTML fragment containing detailed help for the
        /// command, displayed when the end-user executes the 'help command name' command</param>
        /// <param name="postfixType">the postfix type of the command.</param>
        /// <returns>This function always returns True.</returns>
        [XmlRpcMethod("registerCommand")]
        bool RegisterCommand(string url, string name, string description, string help, string postfixType);
        
        /// <summary>
        /// Sets the valid postfixes for a command that takes a bounded
        /// list of postfixes.  The command must have been previously
        /// registered with registerCommand().
        /// </summary>
        /// <param name="url">the URL for the Enso Extension endpoint.</param>
        /// <param name="name">the name of the command.</param>
        /// <param name="postfixes">a list of strings, each representing a valid
        /// postfix for the commmand.</param>
        /// <returns>This function always returns True.</returns>
        [XmlRpcMethod("setCommandValidPostfixes")]
        bool SetCommandValidPostfixes(string url, string name, string[] postfixes);

        /// <summary>
        /// Replaces the user's current selection with unicode text.  If
        /// the user has no current selection, the text is inserted at the
        /// current cursor location in the user's current application.  If
        /// the text cannot be inserted, a transparent message is
        /// displayed and the text is placed in Enso's put buffer.
        /// </summary>
        /// <param name="text">the unicode text to be inserted.</param>
        /// <param name="fromCommand">the name of the command that is inserting the
        /// text. This is entirely for informational purposes and will
        /// be displayed to the user if the text cannot be inserted.</param>
        /// <returns>This function always returns True.</returns>
        [XmlRpcMethod("setUnicodeSelection")]
        bool SetUnicodeSelection(string text, string fromCommand);

        /// <summary>
        /// Unregisters a command.  The command must have been previously
        /// registered with registerCommand().
        /// </summary>
        /// <param name="url">the URL for the Enso Extension endpoint.</param>
        /// <param name="name">the name of the command.</param>
        /// <returns>This function always returns True.</returns>
        [XmlRpcMethod("unregisterCommand")]
        bool UnregisterCommand(string url, string name);
    }
}
